# 自定义UI
从7.0版本开始，Foxit PDF SDK for Web提供了包含功能模块的内置UI框架，该UI框架是通过使用Foxit PDF SDK for Web来实现的，并且封装在UIExtension.js中。此外，自定义UI也非常简单。Foxit PDF SDK for Web为开发人员提供了一组丰富的API，用来自定义web viewer的外观和风格。
UIExtension 的界面由两部分组成：template 和 fragments。Template相当于是对HTML的扩展，在模板中的控件需要通过标签来声明。Template用来自定义无需交互的UI布局 (css样式，图标，文本等) 。Fragments是一组UI snippet，用来自定义模板中的控件的配置项和交互逻辑。每一个snippet都有一个操作类型 "aciton"，其用来指定snippet的作用方式 (append, prepend, before, after, ext, replace, insert, 和 remove，默认是 ext)。通过这些作用方式，您可以向template中插入、删除、替换和修改控件。
# 使用template自定义UI布局
Template主要用来自定义控件的UI布局。以下示例将介绍template的使用方法。所有的示例代码都是基于集成章节的 集成功能完整的webViewer 小节.
# 创建一个简单的template
一个最简单的模板，如下所示：
var pdfui = new UIExtension.PDFUI({
viewerOptions: {
libPath: './lib', // the library path of web sdk.
jr: {
licenseSN: licenseSN,
licenseKey: licenseKey
}
},
renderTo: '#pdf-ui', // the div (id="pdf-ui").
appearance: UIExtension.appearances.Appearance.extend({
getLayoutTemplate: function() {
return [
'<webpdf>',
' <viewer></viewer>',
'</webpdf>'
].join('');
}
})
});
<webpdf>标签会监听文档打开和关闭事件，触发Appearance对象的enableAll和disableAll方法来启用/禁用界面上相关的组件。<viewer>标签是用于渲染PDF内容的地方。每个template都必须含有一个<viewer>标签。该标签可以放置在任何位置，请参考后面的示例代码。
刷新浏览器 (http://127.0.0.1:8080/index.html (opens new window)), 然后您可以看到一个不带其他UI组件的简单web PDF viewer。
# 添加一个工具栏
使用<toolbar>标签添加一个新的工具栏按钮。
var pdfui = new UIExtension.PDFUI({
viewerOptions: {
libPath: './lib', // the library path of web sdk.
jr: {
licenseSN: licenseSN,
licenseKey: licenseKey
}
},
renderTo: '#pdf-ui', // the div (id="pdf-ui").
appearance: UIExtension.appearances.Appearance.extend({
getLayoutTemplate: function() {
return [
'<webpdf>',
' <toolbar>',
' <open-file-dropdown></open-file-dropdown>',
' </toolbar>',
' <viewer></viewer>',
'</webpdf>'
].join('')
}
})
});
刷新浏览器 (http://127.0.0.1:8080/index.html (opens new window)), 然后您可以看到新加的工具栏按钮。
# 添加一个标签页
使用<tabs> 和 <tab>标签来添加一个新的标签页。
var CustomAppearance = UIExtension.appearances.Appearance.extend({
getLayoutTemplate: function() {
return [
'<webpdf>',
' <toolbar>',
' <gtab group="custom-tabs" text="Home" body="home-tab-body">',
' </gtab>',
' <gtab group="custom-tabs" text="Comment" body="comment-tab-body">',
' </gtab>',
' </toolbar>',
' <div class="tab-bodies">',
' <div name="home-tab-body">',
' <open-file-dropdown></open-file-dropdown>',
' </div>',
' <div name="comment-tab-body" class="flex-row">',
' <create-strikeout-button></create-strikeout-button>',
' <create-underline-button></create-underline-button>',
' <create-squiggly-button></create-squiggly-button>',
' <create-replace-button></create-replace-button>',
' <create-caret-button></create-caret-button>',
' <create-note-button></create-note-button>',
' </div>',
' </div>',
' <viewer></viewer>',
'</webpdf>'
].join('')
}
})
var pdfui = new UIExtension.PDFUI({
viewerOptions: {
libPath: './lib', // the library path of web sdk.
jr: {
licenseSN: licenseSN,
licenseKey: licenseKey
}
},
renderTo: '#pdf-ui', // the div (id="pdf-ui").
appearance: CustomAppearance
});
刷新浏览器 (http://127.0.0.1:8080/index.html (opens new window)), 然后您可以看到新添加的标签页。
# 添加一个侧边栏
使用<sidebar>标签来添加一个新的侧边栏按钮。
var CustomAppearance = UIExtension.appearances.Appearance.extend({
getLayoutTemplate: function() {
return [
'<webpdf>',
' <toolbar>',
' <gtab group="custom-tabs" text="Home" body="home-tab-body">',
' </gtab>',
' <gtab group="custom-tabs" text="Comment" body="comment-tab-body">',
' </gtab>',
' </toolbar>',
' <div class="tab-bodies">',
' <div name="home-tab-body">',
' <open-file-dropdown></open-file-dropdown>',
' </div>',
' <div name="comment-tab-body" class="flex-row">',
' <create-strikeout-button></create-strikeout-button>',
' <create-underline-button></create-underline-button>',
' <create-squiggly-button></create-squiggly-button>',
' <create-replace-button></create-replace-button>',
' <create-caret-button></create-caret-button>',
' <create-note-button></create-note-button>',
' </div>',
' </div>',
' <div class="flex-row">',
' <sidebar>',
' <bookmark-sidebar-panel></bookmark-sidebar-panel>',
' </sidebar>',
' <viewer></viewer>',
' </div>',
'</webpdf>'
].join('')
}
})
var pdfui = new UIExtension.PDFUI({
viewerOptions: {
libPath: './lib', // the library path of web sdk.
jr: {
licenseSN: licenseSN,
licenseKey: licenseKey
}
},
renderTo: '#pdf-ui', // the div (id="pdf-ui").
appearance: CustomAppearance
});
刷新浏览器 (http://127.0.0.1:8080/index.html (opens new window)), 然后您可以看到新添加的书签侧边栏。
# 内置布局模板
内置布局模板位于 layout_templates 目录下。桌面端请参考 built-in-pc-layout-template.tpl 文件，移动端请参考 built-in-mobile-layout-template.tpl文件。您可以根据需要直接修改模板来自定义UI。
在 custom_appearance 目录下，Foxit PDF SDK for Web 提供了两个自定义模板示例。 " adaptive-to-the-device.html" 能自适应设备 (桌面端和移动端) ，" not-adaptive-to-the-device.html" 不能自适应设备，仅支持桌面端布局。
# 使用fragments自定义UI
Fragments是一组UI snippet，用来自定义模板中的控件的配置项和交互逻辑。
# 创建一个下拉菜单
下面的示例代码创建一个包含两个drop-down按钮的下拉菜单, 然后将其加入到 "home-tab-group-hand" 组件的子组件列表的末尾。
如何获取目标组件的名称 (只针对widget部件)，您可以在浏览器中右键点击该组件，选择 “审查”， 然后在对应的 <a> 标签中找到 "component-name" 属性的值。对于容器组件，比如target:"home-tab-group-hand", 您可以在浏览器中右键点击其中一个子组件，选择 “审查”，然后在相关的<div> 标签中找到 "component-name" 属性的值。
const customModule = UIExtension.PDFUI.module('custom', []);
customModule.controller('CustomController', {
mounted: function () {
console.info(this.component, 'mounted');
},
handle: function (selectedFile) {
alert(selectedFile.name);
}
});
var CustomController = customModule.getControllerClass('CustomController');
var CustomAppearance = UIExtension.appearances.RibbonAppearance.extend({
getDefaultFragments: function() {
return [{
// Add a component to the end of the list of children of a specified target component.
action: UIExtension.UIConsts.FRAGMENT_ACTION.APPEND,
// Specify the name of the target component that the new components defined in the above template will be appended to. All the target names of fragments are defined in the layout template.
target: 'home-tab-group-hand',
// Define the properties of the added component, such as icon, text, and css style.
template: [
'<dropdown icon-class="fv__icon-toolbar-stamp">',
' <dropdown-button name="show-hello-button" icon-class="fv__icon-toolbar-hand">say hello</dropdown-button>',
' <dropdown-button name="select-pdf-file-button" accept=".pdf" file-selector icon-class="fv__icon-toolbar-open">open</dropdown-button>',
'</dropdown>'
].join(''),
// Define the interaction logic of the added component.
config: [{
// specify the component in the above template that the configuration will be applied to.
// For example, the configuration will be applied to the component with the name of "show-hello-button".
target: 'show-hello-button',
callback: function () {
alert('hello');
}
},
{
// The configuration will be applied to the component with the name of "select-pdf-file-button" which is defined in the above template of fragments.
target: 'select-pdf-file-button',
// Extend Controller, and implement the handle function.
callback: CustomController
}]
}]
}
})
var pdfui = new UIExtension.PDFUI({
viewerOptions: {
libPath: './lib', // the library path of web sdk.
jr: {
licenseSN: licenseSN,
licenseKey: licenseKey
}
},
renderTo: '#pdf-ui', // the div (id="pdf-ui").
appearance: CustomAppearance
});
刷新浏览器 (http://127.0.0.1:8080/index.html (opens new window)), 然后您可以看到新添加的下拉菜单，.
# 删除已有工具栏按钮
通过fragment删除一个工具栏按钮是非常简单的。比如，删除手型工具，您只需要向fragment中添加一个新的对象。添加如下的代码：
{
target: 'hand-tool',
action: UIExtension.UIConsts.FRAGMENT_ACTION.REMOVE
}
刷新浏览器 (http://127.0.0.1:8080/index.html (opens new window)), 然后您可以看到手型工具已被移除，如下所示：
# 修改已有工具栏按钮
通过fragment修改一个工具栏按钮也是非常简单的。类似 删除已有工具栏控件 章节，您只需要向fragment中添加一个新的对象。
# 修改按钮的图标
例如，修改手型工具的图标，只需要添加如下的代码
{
target: 'hand-tool',
config: {
iconCls: 'fv__icon-toolbar-note' // your custom icon.
}
}
刷新浏览器 (http://127.0.0.1:8080/index.html (opens new window)), 然后您可以看到手型工具的图标已被修改.
# 修改按钮的工具提示信息
例如，修改手型工具的工具提示信息，只需要添加如下的代码：
{
target: 'hand-tool',
config: {
tooltip: {
title: 'your custom tooltip'
}
}
}
刷新浏览器 (http://127.0.0.1:8080/index.html (opens new window)), 然后您可以看到手型工具的工具提示信息已被修改为 “your custom tooltip”。
# 修改按钮的事件
有两种方法用来修改按钮的事件：
- 覆盖内置的事件。比如：
{
target: 'hand-tool',
config: {
callback: function() {
alert('your click event handler');
}
}
}
- 基于原有内置事件的逻辑基础上，添加自定义行为。可以使用如下的方式进行配置：
{
target: 'hand-tool',
config: {
callback: {
before: function (handleMethodArguments ) {
console.info('called before handle callback with arguments: ', handleMethodArguments);
},
after: function (value, handleMethodArguments ) {
console.info('called after handle callback with returning value and arguments: ', value, handleMethodArguments);
}
}
}
# 其它示例
有关更多示例代码，请参阅 fragment_usage 目录下的示例。
# 模块化
为了区分内置组件和用户自定义组件以避免冲突，UIExtension提供了模块化功能，可以将组件分别注册在不同的模块中。然后，在template中声明组件时加上模块名前缀。
# 创建自定义模块
如果您需要定义和使用和内置组件同名的自定义组件，您可以首先创建一个自定义模块，然后在该模块中注册自定义组件。
例如，在内置组件中已经存在一个名为"dropdown"的组件，如果您需要定义一个同名的自定义组件，您可以参考以下的示例:
创建一个新的模块"my-widgets"，然后在该模块中注册一个自定义组件：
// Create a new module. Please note that the second parameter must be an array if you create a new module.
var module = UIExtension.modular.module('my-widgets', []);
function UserDefinedDropdownComponent() {
UIExtension.Component.apply(this, arguments);
}
UserDefinedDropdownComponent.getName = function() {
return 'dropdown'; // Declare the tag name of the component. There is already an existing component with the same name of 'dropdown' in the built-in component.
}
UserDefinedDropdownComponent.prototype.constructor = UIExtension.Component;
UserDefinedDropdownComponent.prototype.render = function() {
UIExtension.Component.prototype.render.call(this);
this.element.innerText = 'User-defined dropdown component';
}
module.registerComponent(UserDefinedDropdownComponent);
然后，内置dropdown组件和自定义dropdown组件可以使用如下的方式进行区别：
<!-- built-in dropdown -->
<dropdown></dropdown>
<!-- user-defined dropdown -->
<my-widgets:dropdown></my-widgets:dropdown>
例如，使用自定义dropdown组件：
var pdfui = new UIExtension.PDFUI({
// Omit other parameters.
appearance: UIExtension.appearances.RibbonAppearance.extend({
getDefautFragments: function() {
return [{
action: UIExtension.UIConsts.FRAGMENT_ACTION.APPEND,
target: 'home-tab-group-hand',
template: '<my-widgets:dropdown></my-widgets:dropdown>' // use a colon to separate the module name and component name in the template.
}];
}
})
});